home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Cream of the Crop 21
/
Cream of the Crop 21 (Terry Blount) (October 1996).iso
/
program
/
libkb100.zip
/
LIBKB-1.00
/
KB.DOC
< prev
next >
Wrap
Text File
|
1996-07-23
|
19KB
|
511 lines
Markus F.X.J. Oberhumer <markus.oberhumer@jk.uni-linz.ac.at>
===============================================================================
1. Introduction
===============================================================================
libkb is a free, advanced and portable low-level keyboard library
for MSDOS and Linux.
It has the following highlights:
- it's advanced
Allows access to ALL keys and ALL combinations of them.
You can individually test left and right Shift and Control,
Alt and AltGr, cursor keys, the keypad and everything else
you always wanted. Also handles Pause key and Control-Break.
Supports virtual terminal switching under Linux.
Ideal for games and all applications that want
total control over the keyboard.
- it's practical
Builtin kbhit()/getkey() like interface that allows you
to easily read the keyboard for text input, highscore names
or cheat codes.
- it's portable
Works under MSDOS and Linux.
Written entirely in C without assembler code.
Supports Borland C v3.1 and 4.0 (16 bit), Watcom C v10.5 (32 bit),
djgpp v1 + v2 (32 bit) and Linux gcc.
- it's safe
The library tries to remove its keyboard handler when a program
terminates or crashes. For this purpose it installs some intelligent
signal handlers and uses the atexit() function to achieve
a maximum of robustness.
Support for an emergency-exit key sequence is provided - this is
really useful during development.
Interrupt handler memory in virtual memory environments is locked.
- it's easy to use
The core interface consists of only a handful of functions and variables.
Care has been taken not to pollute the global namespace.
Example programs are included as well.
- it's free
Comes with full source code and documentation. And yes, you can
use it in your commercial applications (no GPL restrictions).
And the following restrictions:
- it's americanized
As the library hooks the keyboard interrupt, individual
keys read with kb_getkey() return hardcoded ASCII values
for the scancodes. These are valid for American keyboards only,
e.g. on a German keyboard Y and Z seem exchanged.
In the beginning I had planned to include support for local key
mappings, but this soon started to become too complex.
Most advanced games suffer this problem.
- it's software
Unfortunately the keyboard controller hardware was not
designed with heavy action in mind. This means that there are
various key combinations that cannot be pressed at the
same time - the keyboard controller just won't handle them.
Nevertheless libkb makes all information the hardware is
able to generate available to an application and the test
program shows you when an 'overflow' occurs so that you
can setup safe default keys for your games.
===============================================================================
2. Documentation
===============================================================================
The basic usage of the library is very simple:
- install the keyboard handler with kb_install(0)
- update the keyboard with kb_update()
- access single keys with kb_key(KB_SCAN_xxx)
- you also have quick access to the shift flags with kb_shift()
- if you want to read textual input, use kb_getkey()
- if you want to switch back to standard keyboard behavior,
call kb_remove(). This will be done for you automatically
when the program terminates or crashes.
The flags
---------
Some flags can be passed to kb_install(). Not all of them
are foolproof and you should know what you are doing when
you are using them. Consider taking a look at the source code
for additional information.
Flags that disable default safety features:
KB_FLAG_NO_ATEXIT
Do not install an atexit() handler.
KB_FLAG_NO_SIGNAL
Do not install signals handlers.
KB_FLAG_NO_LOCK
Do not lock interrupt memory.
Flags that enable extra safety features (useful in development):
KB_FLAG_SIGINT
raise SIGINT on Control-C
KB_FLAG_EMERGENCY_EXIT
enable emergency exit: raise SIGINT on LControl-RControl-C and
exit if the SIGINT-handler returns. Under MSDOS this causes
an exit from within an interrupt handler which can be
somewhat dangerous, but it seems to work though.
You should always setup a SIGINT handler when using this.
KB_FLAG_EMERGENCY_SIGALRM
enable SIGALRM emergency exit (this is mainly useful for Linux):
If your program has a bug and it doesn't call kb_update(),
the machine would lock under Linux cause KB_FLAG_EMERGENCY_EXIT
also relies on kb_update(). When this flag is enabled, the
alarm() timer is used to raise SIGALRM if kb_update() is not
called for more than 30 seconds. You should not use SIGALRM
for other purposes when using this flag.
Misc. flags (probably not very useful):
KB_FLAG_LINUX_NO_VT
Linux: virtual terminal switching is disabled
KB_FLAG_LINUX_VT_NO_KEY
Linux: release all keys after virtual terminal switching
KB_FLAG_DJGPP_NO_RM
djgpp: do not install an additional real mode handler
KB_FLAG_REPEAT_OFF
turn off key repeat for kb_getkey()
The keycodes
------------
The keycode-tables were obtained as a result of investigating
the output of kb_bios_getkey() under MSDOS. They are portable
across all platforms and will remain fixed.
The keycode is computed by passing the result of kb_keypress()
or kb_keypeek() to kb_keycode(). You can write your own conversion
routine if you want to add support for local key mappings.
Notes on building libkb
-----------------------
It is really IMPORTANT to check your compiler flags so that
code will be generated that does not insert stack overflow checks !
You should also use a high optimization level in order to use
as many CPU registers as possible and avoid memory access
inside interrupt- and signal handlers.
Notes on using libkb with other libraries
-----------------------------------------
- Linux + svgalib 1.2.x
Though svgalib chains all signals it catches, it does a lot of low-level
things to support virtual terminal switching while in graphics mode.
So be nice and call kb_install() AFTER svgalib has been initialized.
Note that the real initialization does not happen in vga_init() but
the first time you call vga_setmode().
svgalib also doesn't like if you redirect stderr, and you should
not use keyboard_init() from <vgakeyboard.h> after kb_install().
Signals (advanced feature)
-------
To achieve a maximum of robustness, libkb catches (almost)
all signals that cause an exit by default (if a signal is
ignored libkb ignores that signal as well).
If a catched signal gets raised, the signal handler removes
the keyboard handler and chains to the handler it found active
at installation time.
The libkb signal handler expects from the old (chained) handler
- that the program terminates, or
- that the application gets informed that the keyboard is removed
You probably don't need to worry
- if you setup your signals before kb_install()
- if you want to temporary change a signal after kb_install()
- if you want to ignore a signal after kb_install()
You could find the signal interface useful
- if you want to test if libkb installed a handler for a specific signal
- if you want libkb to catch additional signals
- if you want to set your own signal handler after kb_install() and
want to chain to the one of libkb
Memory locking (advanced feature)
--------------
Memory locking functions have been made public as they are of
potential use for all interrupt routines.
They can be used independently from the rest of the library.
The Operating System (OS) and BIOS functions
--------------------------------------------
Please don't get confused:
the OS and BIOS layers have nothing to do with the keyboard
handler. They mainly act as a portability wrapper and are